[% page.title = 'API Method: match items list' 
   page.tab = 'api'
%]

<h2>GET /:user_id/matches/:folder_id/items</h2>
<p>Returns the list of matches (items) from the specified matches folder with a 200 OK HTTP status code.
For each match item (e.g. pc member) a similarity ranked list of all compared items (e.g. papers) is returned.</p>

<h3>URL:</h3>
<code>[% site.url %]/<em>user_id</em>/matches/<em>folder_id</em>/items.<em>format</em></code>

<h3>Formats (<a href="formats">about return formats</a>):</h3>
<code>[% INCLUDE 'api/_formats.phtml' %]</code>

<h3>HTTP Methods (<a href="http-methods">about HTTP methods</a>):</h3>
<code>GET</code>

<h3>Requires Authentication (<a href="authentication">about authentication</a>):</h3>
<code>true</code> &nbsp;if folder's <code>mode</code> property is set to <code>private</code><br/>
<code>false</code> &nbsp;if folder's <code>mode</code> property is set to <code>public</code>

<h3>Parameters:</h3>
<ul>
<li><code>folder_id</code>.  Required. The ID of the matches folder to list the items of.</li>
<li><code>profiles_id</code>.  Optional. The ID of the profiles folder from which the match items listed originated.
This parameter restricts <code>item_id</code> to range over only items that originated from a single profiles folder;
otherwise all items from both profiles folders will be listed.</li>
<li><code><em>sort</em></code>.  Optional. Number of the term data column to sort the returned <code>term</code> statistics on.
Numeric data columns are sorted in descending order. Textual data columns are sorted in ascending alphabetical order.
Values of <code>sort</code> must be one of:
<ul>
<li><code>0</code> for <code>name</code>, the term name (i.e. the text of the word or keyword).</li>
<li><code>1</code> for <code>n</code>, the term occurrences (i.e. the number of times the term occurs in the document).</li>
<li><code>2</code> for <code>tf</code>, the term frequency (i.e. the ratio of <code>n</code> to the total number of term occurrences in the document).</li>
<li><code>3</code> for <code>idf</code>, the inverse document frequency (i.e. <em>log</em><sub>2</sub> of the ratio of the total number of documents to the number of documents in which the term occurs).</li>
<li><code>4</code> for <code>tfidf</code>, the tf-idf score (i.e. the product of <code>tf</code> and <code>idf</code>).</li>
<li><code>5</code> for <code>wg</code>, the global term weight (i.e. the weight for this term across all items in the folder).</li>
<li><code>6</code> for <code>wl</code>, the local term weight (i.e. the weight for this term in this item).</li>
<li><code>7</code> for <code>wtfidf</code>, the weighted tf-idf score (i.e. the product of <code>tfidf</code>, <code>wg</code> and <code>wl</code>).</li>
</ul>
The default when no value is supplied is <code>7</code>.
</li>
<li><code><em>threshold3</em></code>, <code><em>threshold2</em></code>, <code><em>threshold1</em></code>.  Optional. 
  Threshold scores, for which a <code>bid</code> value of 3, 2 or 1 (otherwise 0) respectively, will be assigned to each match item.
  The thresholds partition the matched items (e.g. papers) into four bid categories ranging from 0 (lowest bid) to 3 (highest bid).
  Some experimentation is required to manually determine threshold values that give reasonable numbers of bids of each category.
  <ul>
    <li>
      If the three thresholds are given as numbers between 0 and 1 then SubSift interprets them as score values above which the corresponding bid will be assigned
      (i.e. if <code>score</code> &gt; <code>threshold3</code> then <code>bid</code> = 3; if <code>score</code> &gt; <code>threshold2</code> then <code>bid</code> = 2; if <code>score</code> &gt; <code>threshold1</code> then <code>bid</code> = 1; otherwise <code>bid</code> = 0).
    </li>
    <li>
      If any of the three thresholds are given as numbers greater than 1 then SubSift interprets them as rank values below which the corresponding bid will be assigned 
      (e.g. if <code>threshold3</code> is 5 then the top five ranked items will be <code>bid</code> = 3; if <code>threshold2</code> is 10 then the next 10 most highly ranked items will be <code>bid</code> = 2; if <code>threshold1</code> is 20 then then the next 20 most highly ranked items will be <code>bid</code> = 1; otherwise <code>bid</code> = 0).
      This allows absolute numbers of bids to be assigned for each match (e.g. pc member) based on the ranked list of items (e.g. papers).
    </li>
  </ul>
</li>
<li><code><em>full</em></code>.  Optional. Whether to include the <code>term</code> data in the returned representation of the item.
Values can be either <code>1</code> for true or <code>0</code> for false. The default is <code>0</code>.
<ul>
<li>Example: <code>[% site.url %]/kdd09/matches/pc_papers/items.xml</code></li>
</ul>
</li>
</ul>

<h3>Usage Examples:</h3>
<blockquote>
<h4>cURL (<a href="curl">about cURL</a>):</h4>
<code>curl [% site.url %]/kdd09/matches/pc_papers/items</code><br/>
</blockquote>

<h3>Response (<a href="return-values">about return values</a>):</h3>
<blockquote>
<h4>XML example:</h4>
<pre>[% FILTER html -%]
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <match>
    <name>paper 122</name>
    <created>1278414103</created>
    <description>paper title removed to preserve confidentiality</description>
    <document_n>92</document_n>
    <item>
      <name>Thomas Seidl</name>
      <score>0.0362320514701348</score>
    </item>
    <item>
      <name>Peer Kroeger</name>
      <score>0.0304853783732565</score>
    </item>
    <item>
      <name>Martin Ester</name>
      <score>0.0207294825179125</score>
    </item>
    .
    .
    .
    <item>
      <name>Sanmay Das</name>
      <score>0</score>
    </item>
    <modified>1278414103</modified>
    <profiles_id>papers</profiles_id>
    <source>text</source>
  </match>
  <match>
    <name>paper 422</name>
    <created>1278414103</created>
    <description>paper title removed to preserve confidentiality</description>
    <document_n>96</document_n>
    <item>
      <name>Hui Xiong</name>
      <score>0.0342672227802433</score>
    </item>
    .
    .
    .
  </match>
  .
  .
  .
  <match>
    <name>Ada Fu</name>
    <created>1268566203</created>
    <description>Ada Fu</description>
    <document_n>2418</document_n>
    <item>
      <name>paper 702</name>
      <score>0.0268317206661247</score>
    </item>
    <item>
      <name>paper 11</name>
      <score>0.0252243523574359</score>
    </item>
    <item>
      <name>paper 387</name>
      <score>0.0243183759127017</score>
    </item>
    .
    .
    .
    <item>
      <name>paper 422</name>
      <score>0</score>
    </item>
    <modified>1268566203</modified>
    <profiles_id>pc</profiles_id>
    <source>http://dblp.uni-trier.de/db/indices/a-tree/f/Fu:Ada_Wai=Chee.html</source>
  </match>
  .
  .
  .
  <match>
    <name>Zoran Obradovich</name>
    .
    .
    .
  </match>
</result>
[% END %]</pre>
</blockquote>

